home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 026-050 / scopedisk29 / xicon2 / docfiles / manual < prev    next >
Text File  |  1995-03-18  |  21KB  |  446 lines
  1. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  12 May 1987
  2.  
  3.  
  4.              XICON  --   Execute Command File from an Icon
  5.  
  6.  
  7. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  8.  
  9.       Copyright (c) 1986, 1987 by Pete Goodeve -- All Rights Reserved
  10.  
  11.    Permission is granted to distribute or modify these programs freely,
  12.    provided that no charge is made for their use, and that this notice
  13.    accompanies them.  For any commercial purposes, please contact the
  14.    author:
  15.                   Pete Goodeve
  16.                   3012 Deakin Street #D
  17.                   Berkeley, Calif. 94705
  18.  
  19. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  20.  
  21. With this program you can execute a file of AmigaDOS CLI commands
  22. directly from a WorkBench window, rather than from the CLI, simply by
  23. double-clicking an associated icon in the window.  A full-screen window
  24. will be opened to display the output of the commands.
  25.  
  26. This is a second release of XICON, with many added features.  You can
  27. now do such things as specify the size of the window (or run without
  28. any window at all), change the title of the window, find the directory
  29. (drawer) the icon was invoked from, and specify other command scripts
  30. besides the one associated with the icon.  You now also get a Close Gadget
  31. on the window.
  32.  
  33. The little text-display program TICON, which was included in the first
  34. release, is now incorporated -- with improvements -- in XICON itself.
  35. (Though for comprehensive display of text there are many better programs
  36. now available; for example 'more' -- included on the 1.2 Enhancer --
  37. can be invoked from a project icon in just the same way as XICON; others
  38. such as 'less' and 'Blitz' which are commonly available can of course be
  39. executed as CLI commands from XICON).  Any simple text file may be used,
  40. provided it is sensibly formatted (with newlines in the right places).
  41.   
  42. The straightforward use of XICON is to have a 'project' type icon
  43. associated with a file of CLI commands (a "script"): when you double-click
  44. on the icon the commands in the file will be executed.  A full-screen
  45. window is opened to display their output.  The window will remain open when
  46. the script is finished until you either click on the Close gadget or type
  47. a control-C (or -D).
  48.  
  49. Many changes can be rung on this basic behavior by adding "Tool Types"
  50. to the icon's info. For example, the window  can be configured to
  51. close automatically by setting the ToolType 'MODE=closewindow' in the
  52. icon.  If none of the commands have any output that you need to see,
  53. set it to "'MODE=nowindow' and the program will not bother to open a
  54. window at all (any output is just thrown away).
  55.  
  56. To set the size of the window that will be opened, use the Tool
  57. Type 'WINDOW=...'.  To change its title at any point in the sequence,
  58. use 'TITLE=...'.  (These options and all the others are described in
  59. detail in their own sections below.)
  60.  
  61. You also have the option of executing commands from the ToolTypes lines
  62. of the icon itself, if you specify them with the 'CMD=...' ToolType.
  63. (There are advantages and disadvantages to this.)  You can specify 
  64. additional command scripts (which will be executed before the one
  65. associated with the icon) with 'SCRIPT=...'.  You can include a remark
  66. to be displayed in the window with 'REM=...', or a text file with
  67. 'TEXT=...'.  You can include as many instances of these particular Tool
  68. Types as you like (unlike configuration settings such as 'MODE' or
  69. 'WINDOW'); they are processed in sequence.  The sequence may include
  70. a wait for a signal from the user with 'PAUSE'.
  71.  
  72. The icon you click on must always have a file associated with it in order
  73. to keep WorkBench happy, but this needn't NECESSARILY be a list of CLI
  74. commands; if you set 'MODE=noscript' it can be any type of data; you can
  75. operate on it if you want with commands in the ToolTypes list.  If you set
  76. 'MODE=text' it will be treated as a simple text file to be displayed a
  77. page at a time in the window.  This replaces the original separate
  78. program 'TICON'.
  79.  
  80. The Tool Type 'LOCDIR=..' lets you specify a file in a known place
  81. (probably RAM:) that will be written with the complete pathname of the
  82. directory containing the icon, so you can overcome the defect in DOS
  83. that loses this information.
  84.  
  85. A very primitive 'choice' mechanism has been added to this version, to
  86. ease the pain of not being able to use DOS conditional commands (IF, etc.)
  87. in the command scripts.  You can take special action if the sequence has
  88. been aborted (except when you cut a test display short) -- see the
  89. description of the 'ABORT-...' Tool Types below.  You can also use the
  90. 'EXISTS=...' Tool Type to see if a file exists, and abort if it doesn't.
  91.  
  92. You can select more than one icon at a time if you like, by holding down
  93. the Shift key as you click on each.  Only DOUBLE-click on the LAST selection
  94. (or use the "Open" item in the WorkBench Menu -- see "Introduction to
  95. Amiga").
  96.  
  97.  
  98.  
  99. Text Display:   When XICON is in the text display mode ('MODE=text' or
  100.                 'TEXT=...') the file is displayed a window-full at a time,
  101. assuming a full screen window.  It will also pause if a form-feed character
  102. is encountered.  To continue, type any key or click in the bottom border
  103. of the window.  You can abort display of that file by either clicking in
  104. the Close gadget or typing control-C; it will immediately proceed to the
  105. next operation if any.  You will have to repeat the action to exit XICON
  106. if there are no more operations.  Note that this is different from the
  107. immediate exit that follows a click on the Close gadget in reponse to
  108. a PAUSE Tool Type.
  109.  
  110.  
  111. Setup:   You can install Xicon itself in any convenient directory: you
  112.          could use either the 'C:' directory of your Workbench disk
  113. or a directory on the same disk as the icons.  (It doesn't need an icon
  114. of its own.)  Whichever directory you use, the icons that are going to
  115. invoke it must have a matching pathname as their DEFAULT TOOL (see below).
  116.  
  117. You can put an icon and its associated file in any directory ("drawer")
  118. that you can open under WorkBench.  The file must of course have the same
  119. name as the icon (without the '.info' extension the icon has tacked on).
  120. Each icon must be of type 'PROJECT' with a DEFAULT TOOL string specifying
  121. a path to the Xicon program.  If it is in the same directory, 'xicon' will
  122. suffice, otherwise you must use the complete pathname.  A full pathname
  123. always begins with the "device name", which is either an actual device
  124. (e.g. DF0: or RAM:) or an assigned name (e.g. SYS: or C:). (See the DOS
  125. manual.)  If the icons are on the same disk as xicon, the device can be
  126. simply ":" (the colon character alone); for example, if the program
  127. 'xicon' is in the directory 'xicon' on the same disk as the icon,
  128. the default tool pathname would be:
  129.  
  130.                     :XICON/XICON
  131.  
  132.  
  133.  
  134. Command Scripts:  There are many ways to generate Command Script files
  135.                   with their icons.  One simple approach is to duplicate
  136. the "democommand" supplied and rename it (using WorkBench Menu operations),
  137. then go to the CLI and modify the text file using whatever editor you are
  138. comfortable with.  If xicon is not in the appropriate directory, you will
  139. also have to change the Default Tool in the icon to the correct pathname
  140. (see below for how to do this).
  141.  
  142. Alternatively you can create the text file first (let's call it 'myscript'),
  143. then use the CLI to copy a suitable project icon ('democommand.info' for
  144. instance) to 'myscript.info' and modify it as necessary.
  145.  
  146.  
  147.  
  148. Modifying an icon:   All the changes you should need to make to an icon
  149.                      (except change its appearance! -- the Icon Editor
  150. is one way of doing that) can be done with the 'Info' item in the WorkBench
  151. Menu.  Select the icon you want to modify by clicking on it, depress the
  152. right mouse button to bring up the menu, and select 'Info' from the
  153. 'WorkBench' section.  This should bring up an information window for
  154. that icon.
  155.  
  156. To set the DEFAULT TOOL, click in that gadget and type in (or edit) the
  157. string.
  158.  
  159. To enter a new TOOL TYPE, click first on the ADD gadget, then click in the
  160. string gadget and type it in.  If you want to insert it into an existing
  161. set, use the arrow gadgets on the left to move to the desired point first.
  162. You can of course edit the strings in the usual way.  Use the DEL gadget
  163. to remove a line completely.
  164.  
  165. When you are done, click in the SAVE box to preserve the changes.
  166. Note that there is a highly annoying bug in the current release of
  167. WorkBench: very often the set of Tool Types you enter into the icon
  168. gets screwed up -- apparently the string terminator gets lost on some
  169. entries, causing the next string to be tagged on.  I haven't established
  170. the exact circumstances, but the only fix seems to be to go back to the
  171. Info, re-edit all your Tool Types, and try saving again.  Eventually
  172. this should work.
  173.  
  174.  
  175. MODE Setting:     You can alter the assumptions made by Xicon by setting the
  176.                   Tool Type 'MODE'.
  177.  
  178.       'MODE=closewindow' avoids having to use control-C or the Close
  179.       gadget to terminate the program.  The window will close as soon
  180.       as all the commands have completed.
  181.  
  182.       'MODE=nowindow' tells XICON not to open any window at all.  Any
  183.       output from executing commands is simply thrown away (sent to NIL:).
  184.  
  185.       'MODE=noscript' prevents Xicon from trying to read commands from
  186.       its associated file, so this can be of any type.  This option only
  187.       makes sense if the 'CMD=' Tool Type is used to supply the commands.
  188.  
  189.       'MODE=text' indicates that the associated file is text, and should
  190.       be displayed a window-full at a time.  
  191.  
  192. Only one MODE entry will be recognized in the Tool Types array, so if you
  193. want more than one of the above options, you must specify them separated
  194. by the vertical-bar character, for example: 'MODE=noscript|closewindow'.
  195.  
  196.  
  197. Modifying the Window:   You can specify the size, position and title of
  198.                         the window that XICON opens by setting the
  199. Tool Type 'WINDOW=xxx/yyy/www/hhh/Title', where xxx and yyy are the
  200. co-ordinates of the top left corner, www and hhh are width and height,
  201. and Title is the desired name for the window.  In other words this is
  202. just the string you would use to specify a 'CON:' window from the CLI,
  203. WITHOUT the 'CON:' prefix itself.
  204.  
  205.       You can't change the size or position of the window once it has
  206. been opened, but you can change its title.  Just include the Tool Type
  207. 'TITLE=title string'.  You can use this more than once in a sequence
  208. (of Tool Type commands -- see below) if you want.
  209.  
  210.  
  211. Commands in the Icon:   Instead of a script file, you can specify commands
  212.                         directly in the Tool Types array of the icon, with
  213. the 'CMD=command string' format.  (For example: 'CMD=list df1:work'.)
  214.  
  215. Include as many of these as you like.  They will be executed in sequence,
  216. but each by a separate CLI process, so you can't use a command to set
  217. parameters like stack size or current directory for the ones that follow.
  218. A Command Script file on the other hand is executed completely by one
  219. process, so settings are inherited.
  220.  
  221. If you want to execute additional command script files before the one
  222. associated with the icon (if any), use 'SCRIPT=filename'.  As usual,
  223. 'filename' may either be the name of a script file in the same directory
  224. as the icon, or it may be the complete pathname of such a file.  These
  225. lines may be interspersed with 'CMD=..' lines (or others) and will be
  226. taken in their turn.  Again, each 'SCRIPT=..' is handled by a separate
  227. CLI process.
  228.  
  229.  
  230. Finding the Directory:     An unfortunate problem of executing commands
  231.                            in this fashion is that the new CLI has no
  232. idea of which directory it was called from.  To overcome this, XICON
  233. has the Tool Type 'LOCDIR=filename'.  If you include this in the icon,
  234. the specified file will be created and filled with a text string giving
  235. the complete path name of the directory containing the icon.  Commands
  236. in the script can refer to this file -- which should be in a known place
  237. such as RAM: -- to take appropriate action.  The string is always enclosed
  238. in quotes, and has a newline character at the end.  DOS commands such
  239. as CD or DIR can read this string simply by redirecting their input and
  240. prompting with '?' (for commands like CD which don't have any needed
  241. output you can suppress the prompt by redirecting output to NIL:).
  242.  
  243. For example, include in the icon info:
  244.  
  245.              LOCDIR=RAM:my_icon_dir
  246.  
  247. then start your script with the sequence:
  248.  
  249.              CD <RAM:my_icon_dir >NIL: ?
  250.  
  251. and you are now working in the right directory.  For neatness, you should
  252. also delete the file before you end the command script.  It is best to
  253. choose unique file names if you are likely to be running more than one
  254. icon at a time.
  255.  
  256.  
  257.  
  258. Other Tool Types:       You have various other actions that you can
  259.                         request with Tool Type strings.  They may be
  260. intermixed with the previous types.
  261.  
  262.        'TEXT=filename' displays the specified file in the window, in
  263.        the same way that 'MODE=text' does for the main file.
  264.  
  265.        'REM=text' displays the text line as a remark at that point.
  266.  
  267.        'PAUSE'  (Note -- no "="!) pauses the sequence at that point,
  268.        as if a form-feed had been encountered in a text file.
  269.        Continue by clicking in the bottom border of the window or
  270.        typing any key.  If you click in the Close gadget instead,
  271.        or type control-C, all remaining Tool Type commands will be
  272.        skipped except 'RESTORE' and those with the 'ABORT-' prefix.
  273.  
  274.        'RESTORE' is only relevant if the sequence has been aborted.
  275.        If it is is encountered it removes the abort condition;
  276.        Tool Type commands and the file associated with the icon
  277.        will be executed as normal.
  278.  
  279.        'EXISTS=filename' will set the abort condition (as if the Close
  280.        gadget had been clicked or control-C typed) if the specified
  281.        file doesn't exist.
  282.  
  283.  
  284.  
  285. The 'abort' condition:    If the Close gadget is clicked or control-C
  286.                           typed in response to a PAUSE, or if an
  287. 'EXISTS=...' Tool Type fails, the abort condition will be set;
  288. all further normal Tool Type commands, and execution or display of
  289. the file associated with the icon, will be suppressed.  If the 'RESTORE'
  290. Tool Type is encountered, however, normal operation will be restored.
  291.  
  292. There are a set of alternative Tool Type commands, corresponding to
  293. the normal ones but prefixed with 'ABORT-', that will ONLY be executed
  294. if the abort condition has been set.  The set is:
  295.  
  296.                 ABORT-REM=...
  297.                 ABORT-CMD=...
  298.                 ABORT-TEXT=...
  299.                 ABORT-SCRIPT=...
  300.                 ABORT-PAUSE
  301.  
  302. Note that the last one behaves JUST like normal PAUSE -- in other words
  303. if you click in the Continue gadget or type a key other than control-C
  304. the abort condition is REMOVED.
  305.  
  306. Sequence of Tool Types:     Remember the difference between the Tool Types
  307.                             that control the environment ('MODE=...',
  308. 'WINDOW=...', etc.) and those that are scanned in sequence.  The first
  309. appearance of each of the former will be recognized at startup -- and at
  310. startup only -- so they won't for example be affected by an abort condition.
  311. They may actually be placed anywhere in the set of Tool Types, in any order,
  312. and they will still be recognized.
  313.  
  314. The Tool Types processed at startup are:
  315.  
  316.               MODE=
  317.               WINDOW=
  318.               LOCDIR=
  319.  
  320. Those processed in sequence are:
  321.  
  322.               CMD=
  323.               REM=
  324.               SCRIPT=
  325.               TEXT=
  326.               TITLE=
  327.               PAUSE
  328.               RESTORE
  329.               EXISTS=
  330.               ABORT-...
  331.  
  332. If you misspell a Tool Type name, it will simply be ignored.
  333.  
  334.  
  335. Caveats:
  336.  
  337.  
  338.    An annoying defect is that the "Execute()" system call used by xicon
  339.    loses track of the current directory when invoked by a WorkBench
  340.    program (it switches to DF0:).  The LOCDIR Tool Type has been added to
  341.    overcome this problem, but if you don't use this you will have to
  342.    specify full pathnames.
  343.  
  344.    The "Execute" referred to above is NOT the DOS "EXECUTE" Command, by
  345.    the way, in case anyone is confused.  Actually this system call (and
  346.    therefore xicon)  requires the DOS "RUN" command -- which must be
  347.    available in the "C:" directory -- for its operation.  (Now I'll bet
  348.    you're confused again...)
  349.  
  350.    Because xicon's method of calling Execute() sets up the command
  351.    file as the input stream, the output window cannot be used as a
  352.    console.  So if a command needs keyboard input it must open up its own
  353.    console window using I/O redirection, e.g.:
  354.  
  355.                mycommand <CON:0/100/150/50/input
  356.  
  357.    (It would likely be a program of your own, because DOS commands don't
  358.    usually ask for input, unless you use the "?" option in the command
  359.    line.  Although, for an example, see the "Set Date" command file in this
  360.    directory.)  You might also want to try "EXECUTE CON:0/100/150/50/exec"
  361.    --or whatever you have renamed that command as.  (To get out of the
  362.    mini-CLI you just created, use 'control-\'.)  If you really want to
  363.    create a full new CLI, the best method is 'NEWCLI FROM filename'
  364.    -- see the 1.2 Enhancer Manual.
  365.  
  366.    By the way, this release of xicon is SUPPOSED to be compatible with
  367.    WorkBench 1.1, but I'm afraid I've only really checked it briefly...
  368.  
  369.    The initial stack size is always 4000 bytes.  You can change this in
  370.    your command script with a suitable STACK command.  Note that the
  371.    STACK gadget in the icon Info window does not have any effect.  (Except
  372.    on the stack used by Xicon itself!  I haven't investigated how much
  373.    it needs.)
  374.  
  375.    You cannot interrupt a command sequence with control-C or control-D
  376.    (because the input stream has been diverted), although output can be
  377.    paused with the space bar in the usual way.  Be careful not to write
  378.    a command file that can get "stuck", or you will never be able to
  379.    close that window.  
  380.  
  381.    Unfortunately DOS won't let you use IF, SKIP, QUIT, and so on in
  382.    these command files.  Of  course you can use EXECUTE on a subsidiary
  383.    script file;  alternatively 'NEWCLI FROM scriptfile' also allows
  384.    conditional commands.
  385.  
  386.    You can use the RUN command from a command script, of course, but
  387.    -- unlike when it is invoked from the CLI -- any output from the
  388.    process started by RUN that you would expect to see on the screen
  389.    is instead thrown away.  
  390.  
  391.                            %%%%%%%%%%%%%%%%
  392.  
  393.  
  394.  
  395.  
  396. Coda
  397.  
  398. I hope you find these programs useful.  If you do, please pass them around
  399. freely.  I'm not asking any specific contribution for this program, but if
  400. you find it useful -- and approve of the Shareware concept -- I would be
  401. pleased no end if you decided to send me $5 or $10  (my address is in the
  402. copyright notice at the top).  I'm also glad to get comments -- positive
  403. OR negative.
  404.  
  405. I suggest you copy the entire drawer -- with its demo and source
  406. files -- by dragging its icon to another disk.  (You won't see either the
  407. programs or their sources in the WorkBench window; they don't have icons.
  408. You can only get at them using the CLI.)
  409.  
  410. If you use the CLI and are fed up with its limitations (no cursor editing,
  411. having to use EXECUTE for command scripts and so on) you might be interested
  412. in a true ShareWare product of mine.  I'm asking $25 if you use it, but
  413. for that you get support -- by mail -- and an update when the next version
  414. now in development is ready.
  415.  
  416. It's a Smart Input Line Interpreter called "Sili(Con:)", and for a start
  417. it lets you enter your commands with full cursor editing facilities.
  418. In addition, previous commands are kept in a VISIBLE history list; you
  419. can recall commands from this list for re-execution and/or re-editing,
  420. either by moving through the list with the up and down arrow keys or
  421. directly by clicking on them with the mouse.  All this takes place in
  422. a window completely separate from the normal Console window where you
  423. see the command output and interact with the programs you invoke; you
  424. can be entering and editing commands while previous ones are chugging
  425. away in the main window.  Real MultiTasking!  If you have a set of
  426. commands you are using repetively, you can invoke them directly from
  427. the history window by double-clicking on them with the mouse.  When you
  428. need to you can push the command window out of the way or bring it back
  429. with a single keystroke.  Also of course you can invoke command scripts
  430. without typing EXECUTE (or your usual abbreviated equivalent!).
  431.  
  432. If you are interested in Sili(Con:), it is available from many sources.
  433. It is downloadable from several of the commercial data services, and is
  434. on disks from users groups and distributors of Public Domain software
  435. and ShareWare such as Fred Fish (disk #50 in his case).  If all else
  436. fails, you can order it directly, for $25 plus $3 p&p (Calif. residents
  437. add 6.5% sales tax) from
  438.  
  439.             Winners Circle Systems
  440.             2618 Telegraph Avenue
  441.             Berkeley, California 94704
  442.             [Tel: (415) 845-4814]
  443.  
  444.                           ##############
  445.  
  446.